Skip to content

Stamp nested blocks and list items with source lines - #263

Merged
dereuromark merged 2 commits into
masterfrom
feature/nested-source-lines
Jul 18, 2026
Merged

Stamp nested blocks and list items with source lines#263
dereuromark merged 2 commits into
masterfrom
feature/nested-source-lines

Conversation

@dereuromark

Copy link
Copy Markdown
Contributor

Follow-up to #262.

What

Extends opt-in source-line tracking (sourceLines: true) from top-level blocks to nested blocks: content inside blockquotes, divs, list items, footnotes, and definition lists is now stamped with data-source-line too, along with <li>, <dt>, and <dd> nodes themselves.

echo (new DjotConverter(sourceLines: true))->convert("- first\n\n  second\n");
<ul data-source-line="1">
<li data-source-line="1">
<p data-source-line="1">first</p>
<p data-source-line="3">second</p>
</li>
</ul>

Why

Editor scroll-sync needs dense anchors. With top-level-only stamping, a document that is one long list or blockquote yields a single anchor, so sync inside it degrades to interpolation over the whole container. Now every item and nested block is an anchor.

How

  • parseBlocks() / parseBlocksImpl() accept an optional per-line map (local index to 0-based document line, -1 for synthetic lines that must not stamp). Built at every extraction site: blockquote prefix stripping, div fences, list item/sublist gathering (including the synthetic blank-line separator), footnotes, definition lists. Maps compose through arbitrary nesting (list in quote, etc.).
  • li/dt/dd are created outside the block dispatch loop and stamped where constructed. An empty <dd> (term without definition) anchors to its term's line.
  • Raw HTML blocks and comments stay unstamped; author-set data-source-line attributes are never overwritten.
  • Content parsed through the public parseBlockContent() helper (custom block callbacks) has no document positions and is mapped as unknown, so nested custom content is not mis-stamped with local indices (found by review).

Behavior / performance

  • Option off (default): output byte-identical. The map bookkeeping is below measurement noise on a container-heavy ~1200-line document.
  • Option on: same attribute path as before, denser stamping. No BC concerns (opt-in, attribute-only).

12 new tests (blockquotes incl. lazy continuation, divs, lists/sublists, synthetic separator, quote/list composition, footnotes, definition lists, author override, CRLF, custom blocks, default-off byte-identity).

Source-line tracking (sourceLines: true) previously stamped only the
document's top-level blocks. Nested blocks parsed through rebuilt,
re-indexed line arrays (blockquotes, divs, list items, footnotes,
definition lists) could not be stamped because the local loop index no
longer matched document coordinates.

Thread an optional per-line map (local index to 0-based document line,
-1 for synthetic lines) through parseBlocks() recursion and build it at
every extraction site. Stamp nested blocks plus li/dt/dd nodes; keep raw
HTML blocks and comments unstamped and never overwrite an author-set
data-source-line attribute. Content parsed via the public
parseBlockContent() helper carries no document positions, so it is
mapped as unknown instead of mis-stamping local indices.

Default output is unchanged; the map bookkeeping in the default case is
below measurement noise on container-heavy documents.
@dereuromark dereuromark added the enhancement New feature or request label Jul 18, 2026
@codecov

codecov Bot commented Jul 18, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.28302% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.37%. Comparing base (386cb7d) to head (a64e7c3).

Files with missing lines Patch % Lines
src/Parser/BlockParser.php 95.28% 5 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff            @@
##             master     #263   +/-   ##
=========================================
  Coverage     92.37%   92.37%           
- Complexity     3643     3660   +17     
=========================================
  Files           109      109           
  Lines         10307    10379   +72     
=========================================
+ Hits           9521     9588   +67     
- Misses          786      791    +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dereuromark
dereuromark merged commit 2cb432a into master Jul 18, 2026
6 checks passed
@dereuromark
dereuromark deleted the feature/nested-source-lines branch July 18, 2026 12:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant